Amiga Collections: Franz PD

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Collections: Franz PD / Franz PD Disk #279 (1993)(Rhein-Sieg-Soft).zip / Franz PD Disk #279 (1993)(Rhein-Sieg-Soft).adf / ak_gen0-lib_V38.20.LHA / ak_gen0-library / Programmers.LHA / Programmers / AK_GEN0-Lib_Reference.doc next >

Wrap

Text File | 1993-07-30 | 25KB | 1,307 lines

AK_GEN0-Lib_Reference.doc V38.1, 30 July 1993 © 1989-93 by Andreas R. Kleinert. All rights reserved. Andreas R. Kleinert Grube Hohe Grethe 23 D-57074 Siegen Germany Here is a listing of all the functions in the style of the 'RKM' : IMPORTANT NOTE : All Parameters are STACK-Parameters, because often there are too many parameters, which won't fit all into the registers. See Doc-File "ReadMe_AK_gen0.txt" for more and detailed information. If you are not sure, since which version a specific function is first available : Use the version number of the Include-File "ak_gen0.h", which is "#define"d there. ----------------------------------------------------------------------------- NAME AK_Screen SYNOPSIS struct Screen * AK_Screen(long l, long t, long w, long h, long d, long dp, long bp, long vm, long ty, struct TextAttr *f, char *title, struct BitMap *cbm); FUNCTION Tries to open a Screen, which is described by the given parameters. INPUT(S) l, t, w, h - LeftEdge, TopEgde, Width, Height of struct NewScreen d - Depth of struct NewScreen dp, bp - DetailPen, BlockPen of struct NewScreen vm - ViewModes of struct NewScreen ty - Type of struct NewScreen f - Font of struct NewScreen title - DefaultTitle of struct NewScreen cbm - CustomBitMap of struct NewScreen RESULT A pointer to a new opened screen or NULL, if opening failed. WARNING Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Window ----------------------------------------------------------------------------- NAME AK_Window SYNOPSIS struct Window * AK_Window(long l, long t, long w, long h, long d, long b, long idcmp, long flags, struct Gadget *fg, struct Image *cm, char *title, struct Screen *screen, struct BitMap *bm, long minw, long minh, long maxw, long maxh, long type) FUNCTION Tries to open a Window, which is described by the given parameters. INPUT(S) l, t, w, h - LeftEdge, TopEgde, Width, Height of struct NewWindow d, b - DetailPen, BlockPen of struct NewWindow idcmp - IDCMPFlags of struct NewWindow flags - Flags of struct NewWindow fg - FirstGadget of struct NewWindow cm - CheckMark of struct NewWindow title - Title of struct NewWindow screen - Screen of struct NewWindow bm - BitMap of struct NewWindow minw - MinWidth of struct NewWindow minh - MinHeight of struct NewWindow maxw - MaxWidth of struct NewWindow maxh - MaxHeight of struct NewWindow type - Type of struct NewWindow RESULT A pointer to a new opened window or NULL, if opening failed. WARNING Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Screen ----------------------------------------------------------------------------- NAME AK_Menu SYNOPSIS struct Menu * AK_Menu(struct Menu *next, long l, long w, long flags, char *name, struct MenuItem *item) FUNCTION Allocs and fills out a "Menu"-structure. INPUT(S) next - NextMenu of struct Menu l - LeftEdge of struct Menu w - Width of struct Menu flags - Flags of struct Menu name - MenuName of struct Menu item - FirstItem of struct Menu RESULT A pointer to an initialized "Menu"-structure or NULL, if failed. WARNING a) First initialize the items in reverse order, then the menus in reverse order. b) Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_MenuItem, AK_SubItem ----------------------------------------------------------------------------- NAME AK_MenuItem SYNOPSIS struct MenuItem * AK_MenuItem(struct MenuItem *next, long t, long w, long flags, long me, APTR itfi, APTR sefi, long scut, struct MenuItem * subi) FUNCTION Allocs and fills out a "MenuItem"-structure. INPUT(S) next - NextMenu of struct MenuItem l - LeftEdge of struct MenuItem t - TopEdge of struct MenuItem w - Width of struct MenuItem flags - Flags of struct MenuItem me - MutualExclude of struct MenuItem itfi - ItemFill of struct MenuItem sefi - SelectFill of struct MenuItem scut - Command of struct MenuItem subi - SubItem of struct MenuItem RESULT A pointer to an initialized "MenuItem"-structure or NULL, if failed. WARNING a) First initialize the items in reverse order, then the menus in reverse order. b) Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Menu, AK_SubItem ----------------------------------------------------------------------------- NAME AK_SubItem SYNOPSIS struct MenuItem * AK_SubItem(struct MenuItem *next, long l, long t, long w, long flags, long me, APTR itfi, APTR sefi, long scut, struct MenuItem *subi) FUNCTION Allocs and fills out a "MenuItem"-structure (here used for a SubItem). INPUT(S) next - NextMenu of struct MenuItem l - LeftEdge of struct MenuItem t - TopEdge of struct MenuItem w - Width of struct MenuItem flags - Flags of struct MenuItem me - MutualExclude of struct MenuItem itfi - ItemFill of struct MenuItem sefi - SelectFill of struct MenuItem scut - Command of struct MenuItem subi - SubItem of struct MenuItem RESULT A pointer to an initialized "MenuItem"-structure or NULL, if failed. WARNING a) SubItems have to be initialized before the main MenuItems. b) Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Menu, AK_MenuItem ----------------------------------------------------------------------------- NAME AK_Gadget SYNOPSIS struct Gadget * AK_Gadget(struct Gadget *next, long l, long t, long w, long h, long flags, long act, long type, APTR gadr, APTR selr, struct IntuiText *text, APTR sp, long id) FUNCTION Allocs and fills out a "Gadget"-structure. INPUT(S) next - NextMenu of struct Gadget l - LeftEdge of struct Gadget t - TopEdge of struct Gadget w - Width of struct Gadget h - Height of struct Gadget flags - Flags of struct Gadget act - Activation of struct Gadget type - GadgetType of struct Gadget gadr - GadgetRender of struct Gadget selr - SelectRender of struct Gadget text - GadgetText of struct Gadget sp - SpecialInfo of struct Gadget id - GadgetID of struct Gadget RESULT A pointer to an initialized "MenuItem"-structure or NULL, if failed. WARNING a) Values for GadgetRender, SelectRender, GadgetText, SpecialInfo have to be initialized before. b) Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Window, AK_Border, AK_IText, AK_StringInfo ----------------------------------------------------------------------------- NAME AK_StringInfo SYNOPSIS struct StringInfo * AK_StringInfo(long groesse, long maximum, struct KeyMap *km) FUNCTION Allocs and fills out a "StringInfo"-structure, which is perhaps later used with "AK_Gadget". INPUT(S) groesse - Size of the Buffer and the Undo-Buffer used by the StringGadget maximum - MaxChars of struct StringInfo km - AltKeyMap of struct StringInfo (normally NULL) RESULT A pointer to an initialized "StringInfo"-structure or NULL, if failed. WARNING a) The memory with the size "groesse" has to be given free with FreeMem later for two times : 1. StringInfo->Buffer 2. StringInfo->UndoBuffer b) Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Gadget ----------------------------------------------------------------------------- NAME AK_Border SYNOPSIS struct Border * AK_Border(long l, long t, long f, long b, long d, long c, WORD *xy, struct Border *next) FUNCTION Allocs and fills out a "Border"-structure, which is perhaps later used with "AK_Gadget", "AK_MenuItem", "AK_SubItem" or whereever else. INPUT(S) l - LeftEdge of struct Border t - TopEdge of struct Border f - FrontPen of struct Border b - BackPen of struct Border d - DrawMode of struct Border c - Count of struct Border xy - XY of struct Border next - NextBorder of struct Border RESULT A pointer to an initialized "Border"-structure or NULL, if failed. WARNING Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Gadget, AK_MenuItem, AK_SubItem, ... ----------------------------------------------------------------------------- NAME AK_IText SYNOPSIS struct IntuiText * AK_IText(long f, long b, long d, long l, long t, struct TextAttr *font, char *text, struct IntuiText *next) FUNCTION Allocs and fills out a "IntuiText"-structure, which is perhaps later used with "AK_Gadget", "AK_MenuItem", "AK_SubItem" or whereever else. INPUT(S) f - FrontPen of struct IntuiText b - BackPen of struct IntuiText d - DrawMode of struct IntuiText l - LeftEdge of struct IntuiText t - TopEdge of struct IntuiText font - ITextFont struct IntuiText text - IText of struct IntuiText next - NextText of struct Border RESULT A pointer to an initialized "IntuiText"-structure or NULL, if failed. WARNING Test, if the result was NULL, or not ! BUGS - SEE ALSO AK_Gadget, AK_MenuItem, AK_SubItem, ... ----------------------------------------------------------------------------- NAME AK_GfxPrint SYNOPSIS void AK_GfxPrint(struct Window *w, char *text, long x, long y) FUNCTION Prints out a text under use of the "graphics.library" functions "Move" and "Text". INPUT(S) w - a valid pointer to a window, as returned by AK_Window text - a pointer to a null-terminated string x - x-position for the text y - y-position for the text RESULT - WARNING - BUGS - SEE ALSO AK_IntuiPrint SetAPen, SetBPen (in "graphics.library") ----------------------------------------------------------------------------- NAME AK_IntuiPrint SYNOPSIS void AK_IntuiPrint(struct Window *w, char *text, long x, long y); FUNCTION Prints out a text under use of the "intuition.library" function "PrintIText". w - a valid pointer to a window, as returned by AK_Window text - a pointer to a null-terminated string x - x-position for the text y - y-position for the text RESULT - WARNING - BUGS - SEE ALSO AK_GfxPrint SetAPen, SetBPen (in "graphics.library") ----------------------------------------------------------------------------- NAME AK_RefreshDisp SYNOPSIS void AK_RefreshDisp(struct Screen *sc, struct Window *w) FUNCTION Cleans the Display under use of the follwing functions out of "intuition.library" and "graphics.library" : "SetRast()" (Window/Screen) "RefreshWindowFrame()" (Window) "RefreshGadgets()" (Window) INPUT(S) sc - a valid pointer to a screen, as returned by AK_Screen w - a valid pointer to a window, as returned by AK_Window RESULT - WARNING Well, the Display will be erased, so it has to be rewritten with the new (or old) information. The gadgets and the WindowFrame are both refreshed since V35.102. Use this functions carefully, because it just refreshes the things, of which it thinks, that they _should_ be refreshed ... BUGS In former versions there have been some bugs. Since V35.102 this function seems to be fully free of bugs. SEE ALSO "intuition.library", "graphics.library" ----------------------------------------------------------------------------- NAME AK_AutoRequester SYNOPSIS long AK_AutoRequester(struct Window *w, char *obertext, char *jatext, char *neintext) FUNCTION Opens an "AutoRequester", just like in "intuition.library" and gives its result back. INPUT(S) w - a valid pointer to a window, as returned by AK_Window obertext - a pointer to a null-terminated string (above text) jatext - a pointer to a null-terminated string (yes-text) neintext - a pointer to a null-terminated string (no-text) RESULT (see "intuition.library", AutoRequest) WARNING "AutoRequest" uses IntuiTexts. "AK_AutoRequester" just uses strings. This is the main difference you shouldn't forget. BUGS (see "intuition.library", AutoRequest) SEE ALSO (see "intuition.library", AutoRequest) ----------------------------------------------------------------------------- NAME AK_Alert SYNOPSIS long AK_Alert(char *text, long height) FUNCTION Displays an Alert at LeftEdge = 100 and TopEdge = 50 under use of the "intuition.library" function "DisplayAlert". INPUT(S) text - a pointer to a null-terminated string (alert text) height - the Height of the alert-"screen" RESULT TRUE for LEFT-Button, FALSE for RIGHT-Button. Always FALSE for DEADEND_ALERTS, but this functions only produces RECOVERY_ALERTS. (see "intuition.library", DisplayAlert) WARNING Be careful. DeadEnd-Alerts never come back. (see "intuition.library", DisplayAlert) BUGS (see "intuition.library", DisplayAlert) SEE ALSO (see "intuition.library", DisplayAlert) ----------------------------------------------------------------------------- NAME AK_FileRequest SYNOPSIS char * AK_FileRequest(long xpos, long ypos, struct Screen *fscreen, struct Window *fwindow, long ftype) FUNCTION Opens the special "AK_GEN0"-FileRequester, which fully administrates itself and just returns a pointer to a string. Under OS >= V2.04 the "asl.library" is used for that. INPUT(S) x - x-position for the requester-window y - y-position for the requester-window fscreen - a valid pointer to a screen, as returned by AK_Screen fwindow - a valid pointer to a window, as returned by AK_Window ftype - the Type of the Screen "fscreen" as used with "AK_Screen" RESULT A pointer to a null-terminated string (FilePath plus -Name). WARNING The String has to be given free after use. The length for this is defined as "AK_FILEREQ_STRING_LEN" in the Headerfile "AK_GEN0.h". BUGS - SEE ALSO AK_ReadDir ----------------------------------------------------------------------------- NAME AK_ReadDir SYNOPSIS long AK_ReadDir(char *pathname, char **direntry, long *dirtype) FUNCTION This function is mainly used by "AK_FileRequest" to read the contentd of directories. INPUT(S) pathname - Path of directory to read direntry - the address of an array of at least 50 char-pointers, which all point to a separat 40-character-array (at least) direntry - an array of at least 50 (long) integers, which will be- come TRUE for directories and FALSE for files. (Other values, which are defined in the Include-File are _only_ for PRIVATE use inside the FileRequester.) RESULT The number of entries found and read. WARNING Don't forget to alloc and the free the arrays !!! BUGS - SEE ALSO AK_FileRequest ----------------------------------------------------------------------------- NAME AK_WaitKey SYNOPSIS void AK_WaitKey(long rawcode) FUNCTION This Function waits for a special (rawcode) key, but not in a multi- tasking conform way (direct register access). INPUT(S) rawcode - the RawKey-Code to wait for RESULT - WARNING Remember ! This is not multitasking-like ! (But its simple :) BUGS 8) SEE ALSO Register : 0xBFEC01 :> ----------------------------------------------------------------------------- NAME AK_WaitLeft SYNOPSIS void AK_WaitLeft(void) FUNCTION This Function waits for the left MouseButton, but not in a multi- tasking conform way (direct register access). INPUT(S) - RESULT - WARNING Remember ! This is not multitasking-like ! (But its simple :) BUGS 8) SEE ALSO Register : 0xBFE001 :> ----------------------------------------------------------------------------- NAME AK_GetNum SYNOPSIS long AK_GetNum(long min, long max) FUNCTION Creates some kind of a random number ... :) INPUT(S) min - the left border for number "X" max - the right border for number "X" RESULT number "X" itself. WARNING This function runs as long as it produces such number. BUGS - SEE ALSO - ----------------------------------------------------------------------------- ADDED IN V36 : ----------------------------------------------------------------------------- NAME AK_AllocRequester SYNOPSIS APTR AllocRequester(long flag) FUNCTION Allocates a special Requester-Structure, whose type and default values depend from "flag". It may e.g. be used to allocate a FileRequester-Structure for use with "AK_ExtFileRequest". Modifications of this structure are (in parts) possible. Read the Include-File ! INPUT(S) flag - a flag, which signalizes the type of the structure to allocate. Example : AK_REQTYPE_FILE for a FileRequester. See into the Include-Files for more details. RESULT A pointer to a Requester-Structure. WARNING The Structure has to be given free after use. Just call AK_FreeRequester with its address. BUGS - SEE ALSO AK_ExtFileRequest, AK_ModeRequest, AK_FreeRequester ----------------------------------------------------------------------------- NAME AK_FreeRequester SYNOPSIS void FreeRequester(struct AK_Requester *req) FUNCTION Delocates the special Requester-Structure, which must have been allocated with AK_AllocRequester and may e.g. have been used by AK_FileRequester before. INPUT(S) req - a pointer to the structure RESULT - WARNING Never try to delocate things which have not been allocated with the corresponding functions. BUGS - SEE ALSO AK_AllocRequester, AK_ExtFileRequest ----------------------------------------------------------------------------- NAME AK_ExtFileRequest SYNOPSIS char * AK_ExtFileRequest(struct AK_Request *req) FUNCTION Opens the special "AK_GEN0"-FileRequester, which fully administrates itself and just returns a pointer to a string. Under OS >= V2.04 the "asl.library" is used for that. INPUT(S) req - a data-structure which contains many information about how to construct the Requester. Has to be allocated with "AK_AllocRequester". RESULT A pointer to a null-terminated string (FilePath plus -Name). WARNING The String has to be given free after use. The length for this is defined as "AK_FILEREQ_STRING_LEN" in the Headerfile "AK_GEN0.h". BUGS - SEE ALSO AK_AllocRequester, AK_FreeRequester ----------------------------------------------------------------------------- ADDED IN V37 : ----------------------------------------------------------------------------- NAME AK_GetDirList SYNOPSIS struct AK_DirList * AK_GetDirList(char *dirname, APTR reserved) FUNCTION This function is mainly used by the FileRequester, but may also be used by applications. It reads a directory and writes the content in a List of AK_DirEntry structures, which then can be read. Delocation has to be done with AK_FreeDirList. INPUT(S) dirname - name of a directory, or NULL to get a list of ASSIGNS and VOLUMES. RESULT Pointer to a list of AK_DirEntry-Structures. WARNING The List has to be given free after use. ONLY use AK_FreeDirList for this. BUGS - SEE ALSO AK_FreeDirList ----------------------------------------------------------------------------- NAME AK_FreeDirList SYNOPSIS void AK_FreeDirList(struct AK_DirList *ak_list) FUNCTION Delocates a list with Directory Contents, which has been allocated and initialized by AK_GetDirList before. INPUT(S) ak_list - a pointer to a list of AK_DirEntry-Structures. RESULT - WARNING Only try to free lists, which have been allocated by AK_GetDirList before. BUGS - SEE ALSO AK_GetDirList ----------------------------------------------------------------------------- NAME AK_GetModeList SYNOPSIS struct AK_ModeList * AK_GetModeList(void) FUNCTION Writes information about all available Screen-Modes (names, dimensions, etc.) into a linked List. INPUT(S) - RESULT Pointer to a list of AK_ModeEntry-Structures. WARNING The List has to be given free after use. ONLY use AK_FreeModeList for this. BUGS - SEE ALSO AK_FreeModeList ----------------------------------------------------------------------------- NAME AK_FreeModeList SYNOPSIS void AK_FreeModeList(struct AK_ModeList *modelist) FUNCTION Delocates a linked list with Screen-Mode Information, which has been allocated and initialized by AK_GetModeList before. INPUT(S) ak_list - a pointer to a list of AK_ModeEntry-Structures. RESULT - WARNING Only try to free lists, which have been allocated by AK_GetModeList before. BUGS - SEE ALSO AK_GetModeList ----------------------------------------------------------------------------- NAME AK_ModeRequest SYNOPSIS struct AK_ModeEntry * AK_ModeRequest(struct AK_Request *req) FUNCTION Opens the special "AK_GEN0"-ModeRequester, which fully administrates itself and just returns a pointer to an AK_ModeEntry-Structure. INPUT(S) req - a data-structure which contains many information about how to construct the Requester. Has to be allocated with "AK_AllocRequester". Free it with "AK_FreeRequester" after use. RESULT A pointer to an AK_ModeEntry-Structure. WARNING The returned structure has to be given free after use. (Use something like : FreeMem(AK_ModeEntry, AK_ModeEntry->Length). BUGS - SEE ALSO AK_AllocRequester, AK_FreeRequester ----------------------------------------------------------------------------- ADDED IN V38 : ----------------------------------------------------------------------------- NAME AK_GetMemList SYNOPSIS struct AK_MemList * AK_GetMemList(void) FUNCTION This function is mainly used by the Requesters, but may also be used by applications. It allocates a MemList-Structure, which then can be used with the other memory functions. Delocation has to be done with AK_FreeMemList. INPUT(S) - RESULT Pointer to a list for AK_MemEntry-Structures. WARNING The List has to be given free after use. ONLY use AK_FreeMemList for this. BUGS - SEE ALSO AK_FreeMemList ----------------------------------------------------------------------------- NAME AK_FreeMemList SYNOPSIS void AK_FreeMemList(struct AK_MemList *ak_list) FUNCTION Delocates a list of AK_MemEntries, which has been allocated with AK_GetMemList() and filled via AK_AddMemEntry() or AK_AllocMemEntry() before. INPUT(S) ak_list - a pointer to a list of AK_MemEntry-Structures. RESULT - WARNING Only try to free lists, which have been allocated by AK_GetMemList before. BUGS - SEE ALSO AK_GetMemList, AK_AddMemEntry, AK_AllocMemEntry ----------------------------------------------------------------------------- NAME AK_AddMemEntry SYNOPSIS long AK_AddMemEntry(struct AK_MemList *mlist, APTR pointer, long size) FUNCTION Adds a previously allocated piece of memory to the specified AK_MemList. INPUT(S) mlist - a pointer to a list of AK_MemEntry-Structures. pointer - a pointer to the piece of memory size - the size of the piece of memory RESULT FALSE, if attempt to allocate the memory failed. WARNING Check the results ALWAYS. NOTE : The specified memory block (pointer, size) will be given free, if an addition to the list is not possible (e.g. because there's not enough memory to allocate another memorylist-entry). This is because error-handling becomes easier this way. BUGS - SEE ALSO AK_GetMemList, AK_FreeMemList, AK_AllocMemEntry ----------------------------------------------------------------------------- NAME AK_AllocMemEntry SYNOPSIS APTR AK_AllocMemEntry(struct AK_MemList *mlist, ULONG size, ULONG type) FUNCTION Allocates and adds a piece of memory to the specified AK_MemList. INPUT(S) mlist - a pointer to a list of AK_MemEntry-Structures. size - the size of the piece of memory type - the type of piece of memory RESULT Pointer to the piece of memory. NULL, if attempt to allocate the memory failed. WARNING Check the results ALWAYS. BUGS - SEE ALSO AK_GetMemList, AK_FreeMemList, AK_AddMemEntry -----------------------------------------------------------------------------